Parent | Child | Previous | Next
 
Xbasic

SQL::ArgumentsAdd Method

Syntax

Result_Flag as L = Add(Name as C [,Value as A [, Usage as SQL::ArgumentUsage [,IsNull as L = .f.]]])

Arguments

NameCharacter

The unique name of an argument. See the SQL::Argument class.

ValueAny Type

Optional. The data may be a simple data type (listed below), a character array, or a numeric array.

  • "Blob"
  • "Character"
  • "Date"
  • "Logical"
  • "Numeric"
  • "Short Time"
  • "Time"
UsageSQL::ArgumentUsage

Defines how the argument should be used. See SQL::ArgumentUsage Enumerated Type for more information.

IsNullLogical

Default value is false (.f.). If true (.T.), set this argument to a NULL value. See also SQL::Arguments SetNull Function.

Description

Add an argument to the collection or L Add(SQL::Argument Argument)

The Add() method adds a new argument to a SQL::Arguments object. You can optionally specify the value and usage of the argument. Returns true (.t.) if the operation is successful and false (.f.) if it fails.

Example

dim args as SQL::Arguments
? args.add("city", "Boston")
= .T.

? args.add("state", "MA")
= .T.

? args.ArgumentNumber("state")
= 2

Setting an Argument to NULL

This example demonstrates setting the argument to NULL.

dim args as SQL::Arguments
args.add("nullField", "", SQL::ArgumentUsage::InputArgument, .t.)

? args.find("nullField").isNull
= .T.

Filtering a SQL Query with Arguments Using Add

This script prompts for a value, then returns a filtered list of records.

dim conn as SQL::Connection
dim sql as C
dim vCity as C
dim args as SQL::Arguments

vCity = ui_get_text("City", "Show Customers in what city?")
sql = "select contactname from customers where city = :city Order By CustomerID"

if .not. conn.open("::Name::AADemo-Northwind")
    ui_msg_box("Error", conn.CallResult.text)
    end
end if

if .not. args.Add("city", vCity)
    end
end if

if .not. conn.execute(sql, args)
    ui_msg_box("Error", conn.CallResult.text)
    end
end if

sql_resultset_preview(conn.resultset)
images/add1.png
Results after searching for "Spain".
The ui_msg_box and sql_resultset_preview functions are only available in desktop applications.

Adding an Argument Array

An argument can be an array of values. Array arguments are often used with IN clauses. For example, in the code below an array argument is used to get a list of records with a CustomerID that matches one of the following values: "ALFKI", "BOLID", "FRANK", or "OCEAN". The resulting query is returned as JSON and displayed using showvarjson()

dim sql as c = "SELECT CustomerID, CompanyName FROM Customers WHERE CustomerID IN (:what_customers)"
dim args as SQL::Arguments
dim customers[0] as C
customers.push("ALFKI")
customers.push("BOLID")
customers.push("FRANK")
customers.push("OCEAN")

args.add("what_customers",customers)

dim cn as SQL::Connection
if (cn.open("::Name::AADemo-Northwind")) then
	dim JSON as C
	JSON = cn.toJSON(sql,args)
	showvarjson(JSON)
	cn.close()
end if

Here is the JSON returned by the query:

[
    {
        "CustomerID": "ALFKI",
        "CompanyName": "Alfreds Futterkiste"
    },
    {
        "CustomerID": "BOLID",
        "CompanyName": "Bólido Comidas preparadas"
    },
    {
        "CustomerID": "FRANK",
        "CompanyName": "Frankenversand"
    },
    {
        "CustomerID": "OCEAN",
        "CompanyName": "Océano Atlántico Ltda."
    }
]

See Also